Summary

Four improvements for Windows compatibility, multi-client HTTP server stability, GPU troubleshooting, and per-project collection scoping.

1. Fix: Windows home directory resolution

src/store.ts determined the home directory with process.env.HOME || "/tmp". On Windows, HOME is not a standard environment variable — it's set in Git Bash and WSL, but not in cmd.exe or PowerShell. This caused QMD to silently write its SQLite index to C:\tmp\.cache\qmd\ (or fail entirely), instead of the user's actual home directory.

Fix: Replaced with Node.js's cross-platform os.homedir(), which correctly resolves on all platforms (Windows: C:\Users\<name>, macOS: /Users/<name>, Linux: /home/<name>).

2. Feature: QMD_GPU environment variable

node-llama-cpp ships pre-built CUDA binaries linked against a specific cuBLAS version. When the user's installed CUDA toolkit has a different major version (e.g., the binary needs cublas64_13.dll but CUDA 12.x only ships cublas64_12.dll), GPU initialization crashes with ggml-cuda.cu: CUDA error. Rebuilding from source requires Visual C++ Build Tools, which many users don't have.

Fix: Added QMD_GPU env var to ensureLlama() in src/llm.ts. Users can bypass broken CUDA with:

QMD_GPU=vulkan qmd embed     # Use Vulkan instead of CUDA
QMD_GPU=false qmd embed      # Force CPU-only

Values: cuda, metal, vulkan, false/off/0 (CPU). When not set, behavior is unchanged (auto-detect best GPU).

3. Fix: Per-session MCP HTTP transport

The HTTP server (qmd mcp --http) previously created a single McpServer + WebStandardStreamableHTTPServerTransport pair at startup. All connecting clients shared this one transport, which caused session conflicts:

• Multiple Claude Code instances connecting to the same daemon would interfere with each other's sessions
• Reconnecting after a disconnect could fail because the transport still held state from the old connection
• Session ID collisions between unrelated clients

Fix: Each initialize request now creates a dedicated session — its own transport and McpServer instance — tracked by session ID in a Map. All sessions share the underlying SQLite store (which is already thread-safe). On shutdown, all active sessions are closed cleanly. The /health endpoint now reports the active session count.

4. Feature: URL-based collection routing (/mcp/COLLECTION)

When QMD runs as a shared HTTP daemon (qmd mcp --http --daemon), there's no way to pass per-project environment variables. Different projects may want to search different collections by default.

Fix: The URL path now optionally includes a collection name:

The collection name is extracted on initialize and applied as the default for all searches in that session. The LLM instructions reflect the scoped collection name and document count.

Configuration example — in per-project Claude Code settings (.claude/settings.json):

{
  "mcpServers": {
    "qmd": {
      "type": "http",
      "url": "http://localhost:8181/mcp/my-project-docs"
    }
  }
}

For stdio transport, the QMD_COLLECTION env var provides the same scoping.

Files changed

Test plan

• TypeScript builds cleanly (tsc -p tsconfig.build.json)
• Existing test suite passes (3 pre-existing Windows-only failures unrelated to this PR: symlink tests require admin privileges)
• GET /health returns { sessions: N }
• POST /mcp initializes with all collections, instructions show total doc count
• POST /mcp/RAMP initializes scoped to RAMP, instructions show scoped doc count and collection name
• Multiple concurrent sessions work independently
• QMD_GPU=vulkan successfully bypasses broken CUDA initialization